// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

part of dart.core;

/**
 * 一个用于一次一个、从对象获取元素的接口。
 *
 * for-in结构以透明的方式使用`Iterator`测试迭代是否结束，并获取每个item（或 _element_）。
 *
 * 如果迭代的对象在迭代过程中发生变化，则该行为是未指定的。
 *
 * 最开始，`Iterator`指向第一个元素的位置前面。
 * 因此在访问第一个元素前，迭代器必须提前使用[moveNext]指向第一个元素。
 * 如果指向末尾，之后已经没有元素，[moveNext]将返回false，[current]返回`null`，
 * 并且再调用[moveNext]也将放回false。
 *
 * 下面是迭代器的典型用法：
 *
 *     var it = obj.iterator;
 *     while (it.moveNext()) {
 *       use(it.current);
 *     }
 *
 * **参见：**
 * [library tour](http://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html)
 * 中的
 * [Iteration](http://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#iteration)
 * 章节。
 */
abstract class Iterator<E> {
  /**
   * 移动到下一个元素。
   *
   * 返回true，如果[current]之后还有元素。
   * 返回false，如果之后已经没有元素了。
   *
   * 调用[moveNext]非常安全，即使迭代器已经位于最后一个元素之后。
   * 在这种情况下，[moveNext]会继续返回false，并没有任何影响。
   *
   * 如果迭代因基础集合发生变化被破坏，调用`moveNext`会抛出错误。
   */
  bool moveNext();

  /**
   * 返回当前元素。
   *
   * 返回`null`，如果迭代器还没有移动到第一个元素，
   * 或者迭代器已经移动到[Iterable]的最后一个元素之后。
   *
   * 直到下一次调用[moveNext]之前，`current`的getter方法应该保留当前值，
   * 即使基础的集合已经更新。
   * 在成功调用`moveNext`之后，使用者不需要缓存当前值，除非迭代器继续读取数据。
   */
  E get current;
}
